home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
E.M.Computergraphic Phase 4
/
Phase 4 - Desktop Video Dreams (E. M. Computergraphic)(1996).iso
/
utilities
/
jacosub
/
documentation
/
overview
< prev
next >
Wrap
Text File
|
1996-01-02
|
25KB
|
550 lines
JACOsub: video titling software for professionals
version 2.2
Timed Script Editor and Player
A Product from Unicorn Research Corporation
This document provides an overview of the JACOsub software package
(features, installation, compatibility, script conversion, and product
support). Be sure to read the product support section concerning bug
reports, if you don't read anything else. Other documentation files in
this package are:
JACOsub.doc - Information on actually running the program.
JScripts.doc - Detailed information on the JACOsub script format
specification.
ARexx.doc - Covers ARexx communications with JACOsub.
QuickRef.doc - Quick reference for script commands and directives.
FAQ - Some Frequently Asked Questions, with answers.
Register.doc - Information about registering the software.
WHAT IS JACOsub?
================
JACOsub is a program designed for displaying timed sequences of titles and
graphics over a video. Professional-quality output and flexibility have
been the primary goals since the program's inception. It was originally
written for the Japanese Animation Club or Orlando (JACO) to lay English
subtitles over Japanese-language films and television shows. The program
has spread and grown in popularity due to its extremely flexible script
format, clean multi-buffered title transitions, and other features
described in the next section.
The development of JACOsub has been primarily user-driven. Most of the
program's more interesting features exist because users suggested them.
Because of the valuable input given by so many people, JACOsub has become
an exceptionally powerful program while retaining its initial simplicity
at the same time.
SPECIAL FEATURES OF JACOsub
===========================
* Non-sequential events. Title time ranges may overlap.
* Display graphic images with the text. Time ranges for graphic images
may overlap also. Graphics (IFF pictures or brushes) may be positioned
anywhere on the screen. If you do not need to generate text over
graphics, you can load IFF pictures independently of JACOsub's display.
JACOsub supports AGA graphics!
* Handles all kinds of time units: SMPTE, 1/100 second units, etc.
* Extremely flexible timing script file format, allowing comments, blank
lines, text directives, and global configuration commands. Scripts can
be as simple or as complex as you want. Scripts may even include other
scripts, so you don't have to re-time parts that you use over and over
again.
* Complete script-based control over text position, margins, font, style,
colors, palettes, backshadow, word-wrapping, and justification. You
can even generate anti-aliased outlines and shadows on mono-color text.
Text appearance can be controlled through line directives or with
C-style escape code inside the subtitle text.
* Support for 3rd-party script formats: TurboTitle (.tts), Phoenix
Japanimation Society (.pjs), generic (.tim), Panimator (.pan), Subtitle
(.sub) and ZeroG (.zeg). The Jconvert utility is provided to convert
all these formats to JACOsub (.js) format. JACOsub can read directly
all but .pan, .sub, and .zeg scripts without prior conversion.
* Multi video buffering and page switching. Many titling programs create
a display in a hidden buffer, then blit it to the visible foreground at
the proper time. But the duration of a multi-bitplane blit can be up
to 3 video frames. This can cause disconcerting "flashing" effects.
Both TurboTitle and PJS's software have this problem. JACOsub has a
better way: It uses video-page switching rather than blitting, to
move displays to the foreground. Images appear instantaneously during
the vertical CRT blank interval. Blitting is only used between up to
five hidden video buffers, never on the visible display.
* You can make time shift and drift adjustments "on the fly" while your
script is playing.
* Fully integrated script editor. If needed, video titles may be
positioned graphically with the mouse.
* ARexx support -- other programs can issue commands to JACOsub, and your
JACOsub scripts can execute ARexx scripts while playing. You can even
edit scripts trhough ARexx.
* You can control the Digital Creations SuperGen genlock faders directly
from your script! GVP and Video Toaster genlock fades may be
controlled indirectly through ARexx scripts.
* Robust compiler diagnostics for tracking down problems in your scripts.
Author: Alex Matulich
1515 Jefferson Davis Hwy #820
Arlington, VA 22202-3311
(703) 413-0215
email: matulich_a@SEAA.NAVSEA.NAVY.MIL
Beta Testers: Fred A. Leggett III (JACO), Daric Kozlowski (JACO)
Tom Perry (Phoenix Japanimation Society)
Noel Gamboa (Operation X)
Robert Lowrey (Central Anime)
Roger Ang, Jacob Ellis, Dave Fleming,
Mike Harlock, Tommy Hwang, Ed Sum
Compiler: SAS Amiga C/C++ 6.51
Computer: Amiga 1000 (never say die!) with WorkBench 2.1
AmigaDOS 2.04 ROM hacked in, 2M FAST, 512K CHIP, 30MB C-Ltd HD
SYSTEM REQUIREMENTS
===================
JACOsub will run on any model Amiga computer, either PAL or NTSC.
Recommended hardware requirements:
* At least 1 megabyte RAM, preferably more than 1.5 megabytes
* Two storage devices (2 floppy drives, hard disk and floppy, or RAM disk
and single disk drive)
Recommended software requirements:
* AmigaDOS 2.0 or greater (program WILL run under 1.3; see next section
for caveats concerning 1.3)
* libs: dirrectory should contain
asl.library or req.library (for file requesters)
iffparse.library (for IFF file support; 1.3-compatible version exists)
The program will still run without these libraries.
Additional hardware needed for video work:
* Amiga-compatible genlock (for overlaying computer images onto video)
* Source video device, preferably a laserdisc player
* Videocassete recorder for making master recordings
* Second video monitor is useful but not required.
INSTALLATION
============
After extracting the archive you should have these files (an "I" in the
first column indicates that the file has an icon (.info file) associated
with it).
I README.1st Quick install and run instructions
I CHANGES.TXT List of improvements and bug fixes
I InstallFonts Installs JACOsub's fonts into fonts:
I JACOsub The timing script compiler & player
JACOsub.cfg Empty config file to replace older ones
I jconvert Conversion utility for 3rd-party scripts
proglogo.bbm Initial graphic that appears in the editor
I documentation (subdirectory)
I Overview.doc You're reading it now
I JACOsub.doc Documentation on operating the software
I JScripts.doc JACOsub Script file format specification
I ARexx.doc ARexx communications documentation
I Register.doc Shareware registration instructions
I FAQ Frequently-Asked Questions, with answers
fonts (subdirectory)
JACOsub.font A few high-quality video titling fonts
JACOsub (subdirectory)
18e 18-pixel height monochrome font for clock
29.4C 29-pixel international color outline font
32.4C 32-pixel international outline/shadow font
36.4C 36-pixel international outline/shadow font
JACOsub_superhires.font Titling font for use in SUPERHIRES mode
JACOsub_superhires (subdirectory)
36.4C SUPERHIRES color outline font
rexx (subdirectory)
abortplay.jsrx Demo of ABORTPLAY ARexx command
begintime.jsrx Demo of BEGINTIME ARexx command
loadscript.jsrx Demo of LOADSCRIPT ARexx command
playsetup.jsrx Demo of PLAYSETUP ARexx command
playstart.jsrx Demo of PLAYSTART ARexx command
quit.jsrx Demo of QUIT ARexx command
savescript.jsrx Demo of SAVESCRIPT Arexx command
screentoback.jsrx Demo of SCREENTOBACK ARexx command
screentofront.jsrx Demo of SCREENTOFRONT ARexx command
etc... ...and various others described in ARexx.doc
I scripts (subdirectory)
I demo.js Demonstration script for JACOsub
I idemo.js Secondary script included by demo.js
I JACO.bbm Graphic logo; IFF brush used by demo.js
All you need to do to install the software after you extract the archive,
is copy the supplied fonts to your fonts: directory. To do this, simply
double-click on the "InstallFonts" icon, or enter these commands from the
JACOsub directory at a Shell prompt:
copy fonts fonts: all ;copy the supplied fonts
delete fonts all ;delete the fonts directory created by the
;archive extraction.
THE JACOsub FONTS MUST BE IN YOUR FONTS: DIRECTORY PRIOR TO RUNNING THE
PROGRAM FOR THE FIRST TIME. The fonts get updated and improved
periodically, so you should always re-install them whenever you get a new
version of this software.
If you have a SuperGen genlock, you need to make sure that your LIBS:
directory contains supergen.library and copinit.library. If they are
missing, you won't be able to control your SuperGen from JACOsub scripts.
Before you run the program, you should be aware of some issues concerning
different versions of AmigaDOS:
AmigaDOS 1.2: You will not be able to run JACOsub with color fonts.
If you boot up with a 1.3 disk using 1.2 Kickstart, you may have better
luck. In any case, upgrade to 1.3 or 2.0 as soon as you can. Your
libs: directory should contain req.library. JACOsub does not support
AmigaDOS 1.2; if it works at all, it's purely an accident.
AmigaDOS 1.3: You will need to load a Colortext driver prior to running
JACOsub. A good Colortext driver by InterActive Softworks is supplied
with Deluxe Paint IV or Calligrapher. If you don't load this driver,
you will see only single-colored characters while JACOsub runs.
>> DO NOT USE ColorTextWedge 1.2 (supplied with TurboTitle) -- it forces
all text into JAM2 mode which chops up fonts having overlapping
dropshadows (such as the supplied JACOsub font). Also, your libs:
directory should contain req.library, though it's not required.
>> Under 1.3, JACOsub's IFF capabilities will be unavailable to you unless
you have a 1.3-compatible version of iffparse.library in your libs:
directory.
AmigaDOS 2.0 users do not need any special driver -- it's built into
2.0. You don't need req.library, but your libs: directory should
contain the AmigaDOS asl.library. It's a good idea to patch it with the
reqtools.library patch utility if you have it. Under AmigaDOS 2.s, you
will be unable to load files using AGA video modes.
AmigaDOS 3.0 and above: Should behave the same as AmigaDOS 2.0, except
that you can load IFF files that use AGA graphic modes.
Now you're ready to begin. Just click twice on JACOsub's program icon, or
type "run jacosub" from a Shell prompt. Refer to JACOsub.doc for more
detailed information on operating the program.
INTERACTIONS WITH OTHER SOFTWARE
================================
Directory Opus 4.0:
DO NOT use JACOsub with Directory Opus 4.0! This version of Directory
Opus has some known problems that will cause you much grief if you try
to run JACOsub with it. We recommend you avoid directory utilities
altogether when running JACOsub!
EPU, PowerPacker, and other filesystem compression utilities:
File compressors used to give JACOsub problems before version 1.9 if
the compressor was set to report the compressed sizes of files, rather
than the original, uncompressed size. This no longer matters; disk
compressors should cause no trouble.
Genlocks:
In general, be sure all video sources are off, and your genlock is not
trying to gain a lock on anything, when you boot up your computer.
Genlocks affect the Amiga's internal clocking, and can cause timing
instabilities if you power everything up in the wrong order. GVP
genlocks seem to be especially fussy about how they are brought online.
GVP users: load IFF files with JACOsub at your own risk. There is an
incompatibility between the GVP and the AmigaDOS IFF loader routines.
Contact Great Valley Products for more information and updated software.
SuperGen users should have at least version 2.0 of the supergen.library
and copinit.library. See the GENLOCK SUPPORT section below for details.
Text editors:
Some users have reported that certain text editors, when run in the
background while JACOsub is running, will mess up script timing. We
have had no problems with TxED. Other users have reported no problems
with CED. In any case, it is probably a good idea to shut down
unnecessary tasks before running ANY timing-critical application such
as JACOsub.
req.library:
You should have either asl.library or req.library in your libs:
directory. The program should still work fine without these, however.
Warning: I have observed instances of req.library trashing memory
location $00000078 (in the zero-page memory area) which is dangerous for
AmigaDOS. If your computer crashes right before a file requester should
appear, the fault is with req.library, not JACOsub. JACOsub will use
asl.library if it can be found.
reqtools.library:
Highly recommended! The patch utility that comes with reqtools.library
patches req.library, asl.library, and arp.library to use features in
reqtools.library. It fixes the problem with req.library described
above. Reqtools.library makes your Amiga (and JACOsub) significantly
more pleasant to use.
GENLOCK SUPPORT
===============
SuperGen (Digital Creations)
--------
JACOsub allows your scripts to control the faders on a SuperGen genlock.
You need to have supergen.library and copinit.library in your LIBS:
directory to take advantage of this feature. These libraries are available
from the libs directory of your Digital Creations SuperGen software disk.
SUPERGEN.LIBRARY VERSIONS LESS THAN 2.0 WILL NOT WORK WITH JACOsub.
If your SuperGen library is too old, your fades will results in jittery
dissolves. Update your SuperGen library as soon as possible.
JACOsub will not assume control over the SuperGen until it must execute a
fader command. From that point on, the genlock will be under software
control until the script play terminates, and then control will be returned
to manual mode.
Warning! DO NOT BOOT UP YOUR AMIGA WITH A SIGNAL PRESENT ON THE SUPERGEN'S
VIDEO INPUT!! Doing so will adversly affect the Amiga's system clock,
which will cause your scripts to run erratically or much too fast!
See the G directive in the Script Format Specification documentation
JScripts.doc, for information on controlling the SuperGen. Other genlocks
will be supported as software and documentation becomes available to the
author.
GVP Genlock (Great Valley Products)
-----------
Dissolves with the GVP G-Lock must be controlled through ARexx. JACOsub
will look for the ARexx script "gvpfade.jsrx" in the current directory, a
"rexx" subdirectory under the current directory, and in REXX:, and copy the
script to ram:glfade.jsrx for faster execution. This script is currently
not provided. See the file ARexx.doc for specifications of this script.
If you create such a script, please send it to us!
If you have a GVP Genlock, PLAY SCRIPTS THAT LOAD IFF GRAPHICS AT YOUR OWN
RISK! Your Amiga WILL VERY LIKELY crash! Great Valley Products says that
the normal AmigaDOS IFF loading routines cause problems when the GVP is in
operation. Great Valley Products has their own proprietary IFF loader
routines available, but JACOsub does not support them yet. JACOsub uses
AmigaDOS 2.0 iffparse.library with the standard IFF loader from the ROM
Kernel Devices manual. Set GENLOCK to GVP in your JACOsub.cfg file; this
will cause a compile-time warning to be issued if a script attempts to load
an IFF file. In the future, the GVP setting will enable true GVP support.
Video Toaster (NewTek)
-------------
The first paragraph under "GVP Genlock) above applies to the Video Toaster
also, only the script should be named "toasterfade.jsrx."
General Information
-------------------
Warning! The genlock may sometimes show things that do not appear on the
RGB display. Some examples we discovered:
A vertical line appears on the right edge of genlocked display, but not
on the RGB display. Solution that worked for us: Be sure the
horizontal screen size is a multiple of 32, such as 640, 672, or 704.
Digital Creations tells us that this line won't appear on your
videotape, but we suspect they're talking about a different phenomenon.
Little pieces of characters from the left side of the screen appear
on the right edge. This happens when a character's kern setting causes
the left edge of the screen to clip off a pixel or two, as in the 'W'
and 't' of the 36-pixel JACOsub font. You can see this when you run
the demo script after changing the left margin to 0% by inserting the
line #HL0 at the top of the script. Solution: Use the HL1 directive
instead of HL0, to provide a few pixels of margin space. This will keep
kerned characters from going past the left edge of the display.
AREXX SUPPORT
=============
If you have ARexx, JACOsub will open an ARexx port called 'JACOsub'. You
can use a different program (such as SCALA for example) to issue a number
of commands to JACOsub, and you can have JACOsub execute ARexx scripts
while a JACOsub script is playing. For more information, see the file
ARexx.doc.
SCRIPT CONVERSION UTILITY
=========================
Although JACOsub can read directly TurboTitle and Phoenix scripts, they
won't be able to use many of JACOsub's advanced features. If you need text
with non-sequential, overlapping time ranges, or if you need to control the
positioning or attributes of the text, or if you want to play a Panimator
script with JACOsub, you must convert the script to the JACOsub script
format.
You don't *have* to convert .pjs or .tts scripts to JACOsub format if you
need only to adjust text style or color (green italics, etc.). For these
operations, you can insert style and color codes directly into your text,
and still retain compatibility with your other timing software. Your other
software won't use these codes (they'll get displayed on the screen
instead). See the Script File Format Specification documentation
JScripts.doc for descriptions of the possible codes that you can use.
If you need to convert to JACOsub, it's very simple. The Shell command is
jconvert [-v[erbose]] scriptname1.ext [scriptname2.ext] ...
where .ext can be:
.tts (TurboTitle)
.pjs (Phoenix Japanimation Society)
.tim (Generic)
.pan (Panimator)
.sub (Subtitle)
.zeg (ZeroG)
The optional -v or -verbose switch causes jconvert to echo its output to
the screen as it writes the new file.
To run jconvert from Workbench, you can click on its icon twice. A file
requester will appear, allowing you to select a file to convert. If you
have SCRIPTPATH specified in JACOsub.cfg, jconvert will use this as the
starting directory for the file requester.
Or, if you need to convert multiple scripts, you may multiply select your
script icons (clicking while holding down the SHIFT key) ending with a
double-click on the jconvert icon.
Jconvert will read in the script, and write out a new script file called
scriptname.js which will be in JACOsub format. Then you can modify
scriptname.js to take advantage of JACOsub's advanced features.
Source code for jconvert is available separately. It should work for any
computer or operating system. If you need it, write to the author, check
your local BBS, or call Anime Central BBS (see information at the end of
this document).
NOTICE: We recommend that you let JACOsub try to read your script PRIOR to
converting it with jconvert, because JACOsub can inform you of potential
problems with your script, but jconvert cannot. Jconvert does not analyze
your scripts; it simply converts them blindly. The only exception is when
converting TurboTitle scripts, jconvert will correct overlapping time
ranges by shortening the previous line's end time to be equal to the
current line's start time.
JACOsub SCRIPT FILE FORMAT SPECIFICATION
========================================
See the textfile JScripts.doc for a complete description of the JACOsub
script file format.
About those 3rd-party file formats
----------------------------------
Robert Jenks, the author of TurboTitle, made an excellent suggestion in his
documentation, that the TurboTitle format should be adopted as a standard
for future software. JACOsub is compatible with TurboTitle files, but the
TurboTitle format was just not flexible enough for our needs. We needed to
use SMPTE time units, we needed to control color, style, and positioning of
text, we needed to insert comments in the script and inside the text, and
we needed no restrictions on how time events were sequenced. (We also
needed something that displayed text faster and more cleanly, but that had
nothing to do with the file format.)
The preceding paragraph is not meant to be critical of Mr. Jenks' work.
TurboTitle was a fine program for its time, and it served to provide some
inspirational influence for JACOsub. TurboTitle is still a good program
for timing scripts.
We feel that the JACOsub script file format is the most flexible yet
developed. Scripts can be as simple as TurboTitle scripts, containing only
timing numbers and text, or you can go all out with global commands and
complex directives.
We will follow the example of TurboTitle's author, and ask that the JACOsub
format be adopted as a standard for future titling software products. The
format is flexible enough to evolve and grow, so if you have suggestions
for improvements or changes, please let us know.
And especially, if you want JACOsub to support another file format, tell us
the specifications and we'll try to work it into either the program itself
or the jconvert utility.
SHAREWARE REGISTRATION / COMMERCIAL LICENSING
=============================================
Please refer to the file register.doc.
LEGAL DISCLAIMER
================
(Shamelessly adapted from Haventree's EasyFlow documentation)
We don't claim JACOsub is good for anything -- if you think it is, great,
but it's up to you to decide. If JACOsub doesn't work: tough. If you
lose a million because JACOsub messes up, it's you that's out the million,
not us. If you don't like this disclaimer: tough. We reserve the right
to do the absolute minimum provided by law, up to and including nothing!
This is basically the same disclaimer that comes with all other software
packages, but ours is in plain English and theirs is in Legalese.
Additional disclaimer: The author will attempt to update the software as
needed, but is not obligated to do so.
SUPPORT, TECHNICAL QUESTIONS, SUGGESTIONS, BUG REPORTS
======================================================
You can contact the author, Alex Matulich, at the address at the beginning
of this file. Alex may be reached via email, using the following addresses:
Internet: matulich_a@SEAA.NAVSEA.NAVY.MIL
alex@bilver.oau.org (should automatically forward)
Alex.Matulich@animece.oau.org (last resort)
Fidonet: 1:363/137, name "Alex Matulich" (last resort)
Support BBS: Anime Central 407-645-2241, N-8-1, 14,400 baud max (v.32bis),
Fidonet address 1:363/137.
The latest version of JACOsub, and timed scripts contributed
by JACOsub users, are in the JACOsub Support file area.
Please do not ask questions of the Sysop regarding JACOsub.
Instead please direct all questions to Alex Matulich.
IMPORTANT: WHEN SUBMITTING A BUG REPORT, BE SURE THE PROBLEM IS REPEATABLE
AND SPECIFY THE CONDITIONS UNDER WHICH THE PROBLEM OCCURRED. Too many
people report problems like "the program crashed when I tried to play my
script" with no other information. This kind of report helps nobody! What
version of JACOsub? What version of AmigaDOS? What kind of computer?
What were you doing prior to noticing the problem? Can you reproduce it
and isolate it enough for ME to be able to do the same?
If you encounter a problem, try to isolate it. If the problem is being
caused by something in your script, send the author a small sample script
with your bug report that demonstrates the problem. Try running the program
on another machine -- if it runs fine on another machine, try to determine
what's different about your setup that's causing the trouble. And try to
describe the bug as completely as possible in your report.
If you're still reading this far, thank you for using JACOsub.
End of Overview.doc.